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Abstract 

This manual describes version 1.6 of the programming language hepawk, 
designed for convenient scanning of data structures arising in the simula- 
tion of high energy physics events. The interpreter for this language has 
been implemented in FORTRAN-77, therefore hepawk runs on any machine 
with a FORTRAN-77 compiler. 
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Program Summary 



Title of the program: 
Computer/Operating System: 
Programming language: 
Memory required: 
Number of bits in a word: 
Number of program lines: 
Other programs used: 

Keywords: 

Nature of physical problem: 
Method of solution: 



Typical running time: 



hepawk 

Any with a FORTRAN-77 environment 
FQRTRAN-77 

400k words (including histogramming package) 
32 

re 11000 

HBOOK||, histogramming package from the CERN 
library. 

Language translation, Monte Carlo event generation, 
High energy physics. 

Developing a Monte Carlo event generator for high 
energy physics requires extensive testing by analyz- 
ing its output. 

By implementing an interpreter for a special pur- 
pose language dedicated to scanning the output of 
Monte Carlo event generators, recompilation of the 
FORTRAN-77 program can be avoided. Since the lan- 
guage has special constructs for scanning high energy 
physics events, the desired analysis can be specified 
very concisely. The interpreter is implemented by us- 
ing a parser generator and is therefore easy to main- 
tain and very reliable. 

Depending on the application. Comparable to the 
equivalent straight FORTRAN-77 version. 
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Long Write Up 



1 Introduction 

Developing a Monte Carlo event generator for high energy physics involves a 
substantial amount of testing for different observables and kinematical regions. 
Traditionally this is done by writing a FORTRAN-77 subroutine analyzing the 
event generator's output, which will be modified, recompiled and relinked for 
each set of cuts. To reduce the number of necessary recompilations, one usually 
defines some canonical variables to parameterize the cuts and reads their values 
from a file. 

On the other hand, the latter approach is not very flexible. We therefore 
propose to generalize the standard approach by using a complete programming 
language for specifying the cuts and filling the histograms. In this case, the 
interpreter for the programming language can be linked once and for all with 
the Monte Carlo program under consideration. Furthermore this programming 
language allows a very concise specification of the analyzer, because operators 
and builtin functions for common geometrical calculations are provided. 

At first sight it might seem to be too much effort to create a new program- 
ming language for a specialized task, but a closer inspection shows that this is 
not the case. The theory of translation of programming languages is well estab- 
lished Q and the implementation of simple programming languages has become 
a straightforward exercise (e.g. Q), provided the available tools are used. 

Furthermore, the emergence of standards [0] for passing event information 
between different Monte Carlos allows to create reusable interfaces. Therefore 
the interpreter (or compiler) for an event scanning language can be used un- 
changed for all Monte Carlos adhering to this standard. An added advantage 
of this approach is the decoupling of the Monte Carlo generator from the an- 
alyzing routine. No internal data structures of the generator will be available 
to the analyzer, thus the generator is tested as it will appear to the application 
program. 

This paper describes the implementation of hepawk, a language for scanning 
high energy physics events, hepawk was developed as a back-end for the KRONOS 
Monte Carlo for radiative corrections at HERA Q and has been used extensively 
during the construction of this generator. 

The outline of this write up is as follows: after an introduction to hepawk 
in section ||, we describe in section || the FORTRAN-77 interface. The implemen- 
tation is described in detail in section [| and section || outlines possible further 
developments. A reference manual and a test run are presented in the appendix. 
This manual is an updated version of ||. 

The name hepawk stands for High Energy Physics AWK . The latter is the 
standard UNIX text manipulation and report generation language |6), from 
which hepawk inherited some of its syntax. 

2 Design 

In this introduction we shall describe the design of hepawk and shall informally 
introduce most of the features of hepawk version 1.6. We proceed by discussing 
an example of a complete hepawk script, introducing concepts in the order of 
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appearance. For further details and more complete descriptions, the reader is 
referred to the appropriate section of the reference manual in appendix |A|. 

As already mentioned, hepawk has been designed to meet two distinct pur- 
poses: allow concise specifications of analyzers for Monte Carlo generated events 
and avoid recompilation and relinking of large programs. 

The latter purpose is of course purely technical. However, linking a Monte 
Carlo event generator with a huge library like the CERN library takes a con- 
siderable amount of time on most computer systems. Avoiding this step allows 
to test a Monte Carlo for a broader scope of observables. 

To meet the former purpose, hepawk version 1.6 provides the following fea- 
tures: 

• data structures: vector and particle. 

• vector operators: +, -, *, etc. 

• control structures: for, if - else, while. 

• kinematics: angle (),rap () (rapidity), / 1 (Lorentz transform), etc. 

• simple access to histogramming: bookl (), fill (), etc. 

The availability of these features should pay off for the additional effort of having 
to learn yet another language. Especially the richer set of control structures 
(compared to FDRTRAN-77) and the vector expressions have proven to be very 
convenient. 

It should be noted at this point that most of hepawk's features could easily 
be implemented in a C++ Monte Carlo library Q, where data structures and 
overloaded operators are readily available. 

However, all major Monte Carlo event generators to date are written in 
FORTRAN-77 and interfacing FORTRAN-77 to other languages like C++ is unfortu- 
nately machine dependent. Furthermore, C++ is only available for a small subset 
of the computers used in high energy physics. In contrast, hepawk offers a highly 
portable implementation of these features. The same considerations apply to 
FORTRAN-90, although in this case linkage to FDRTRAN-77 is guaranteed by the 
standard. 

2.1 Features 

hepawk scripts are in free format, with two exceptions: everything from column 
73 to the end of the line will be ignored and the end of the line terminates 
comments. The former restriction is necessary to avoid errors when moving 
hepawk scripts to computers which assume fixed size records in their input 
stream. 

In principle, hepawk does not restrict the complexity of the script. However, 
very complex scripts with deeply nested control structures might exceed the 
size of hepawk's run time stack. In this case, hepawk can easily be recompiled 
with a larger stack. Very long scripts with many variables might need a larger 
size for the memory pool managed by hepawk, this can also be achieved by a 
recompilation. 

Each hepawk script is a sequence of conditions and actions. An action will be 
executed for each event for which the condition evaluates to true (by convention, 
an empty condition is always true). 



4 



hepawk has the builtin datatypes scalar, vector, and particle. Vectors are 
usual Lorentzian four-vectors and the usual arithmetical operators are defined 
for them. Thus the inner product of two vectors $p and $q can be assigned to 
the scalar pq by 

pq = $p * $q; 

The interpretation of the operators +, -, and * is uniquely determined by 
their operands. This feature allows to express kinematical calculations very 
concisely. 

The output of the event generator is accessed by looping over subsets of 
particles in the standard common block. For example 

for (fflp in ELECTRONS) 
{ 

# a group of statements 

# operating on the electron @p 

} 

executes the statements enclosed by the braces for each electron stored by 
the generator in the standard common block. 



The annotated example in section 2.2 is taken from a study of multi photon 



events at HERA, using the KRONOS Monte Carlo m. The script addresses two 
questions: which multiplicity for observed bremsstrahlungs photons is to be 
expected at HER A and what is the energy spectrum of photons in multi photon 
events? 

To answer these questions, it is of course important to take into account 
the detector geometry. This is accomplished by specifying angular ranges for 
the main detector and the two luminosity monitors. These can be implemented 
easily by conditionals of the type 

if (theta_min <= angle ($photon, $z_axis) <= theta_max) 
{ 

# process the event satisfying 

# the above angular cut 

} 

The multiplicity obviously depends on the minimal energy of observed pho- 
tons. In order to collect the multiplicity for several cuts, we have to loop over 
these cuts, using a while iteration: 

E_cut = E_cut_min; 
while (E_cut <= E_cut_max) 
{ 

if ($photon:E >= E_cut) 
{ 

# process the event satisfying 

# the above energy cut 

} 

E_cut = E_cut + E_cut_step; 

} 



2.2 An annotated example 
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2.2.1 The BEGIN action 



The BEGIN action is executed before the first event is processed. Typically it 
defines some variables and allocates histograms. There can be several BEGIN 
actions in a hepawk script, they will be concatenated. 

This BEGIN action starts by printing some information on the Monte Carlo 
run which will be processed. The builtin function printf is simil ar to the 
function with the same name from the standard C library. See section A.8.2] for 
details. 

# multiphoton. hepawk 

BEGIN 
{ 

printf ("\nKR0N0S, y,s:\n", REV); 

printf ("Run: 7„d, Date: 7.s\n\n" , RUN, DATE); 



The builtin variables REV, RUN, and DATE are preset to the version and revi- 
son date of the Monte Carlo, the number of the run, and the date of the run 



respectively. This information is taken from /hepevt/. See section A. 7 for more 
automatic variables. 

Next we introduce variables as symbolic names for kinematical cuts, detector 
geometry, and histogramming parameters. 



x_min = 0.001; x_max = 0.1; Q2_min 



100; 



# kinematical cuts 



E_min = 0.5; E_max = 40 ; 

n_max = 6; E_cut_max = 3; E_ cut _ step 

E_cut_bins = E_cut_max / E_cut_step; 



# histogramming range 
0.1; # multiplicity cuts 



th_min_lumi = 0; th_max_lumi 
th_max_main = PI - 0.100; 
th_min_main = 0.150; 



0.5e-3; # luminosity monitors 

# main detector (fwd) 

# (bwd) 



th_sep_jet = 0.300; 
th_sep_em = 0.150; 



# separation from jet 

# sep. from electron 



Finally we allocate counters and histo grams for the various event types and 
observables we want to study. See section A. 8. 4 for more details on the interface 
to the histogramming package. 

incut_0 =0; # counting photon evts 

incut _1 =0; # counting 1 photon evts 

h_E = bookl (0, "dsigma/dE", E_max, 0, E_max) ; 

incut_2 =0; # counting 2 photon evts 

h_El = bookl (0, "dsigma/dEl" , E_max, 0, E_max) ; 
h_E2 = bookl (0, "dsigma/dE2" , E_max, 0, E_max) ; 

# Multiplicities 
h_m = book2 (0, "Multiplicity", n_max, - 0.5, n_max - 0.5, 

E_cut_bins, 0, E_cut_max) ; 



G 



h_El_E2 = book2 (0, "dsigma/dEldE2" , # Lego plot 

E_max , , E_max , E_max , , E_max) ; 



2.2.2 Kinematics 

The calculation of the basic kinematical variables should be almost self explain- 
ing. This action will be executed for all events, because no selection condition 
is given. 

The basic data types in hepawk version 1.6 are real, vector, and particle. The 
lexical convention is to use identifiers starting with $ for vectors and identifiers 
starting with @ for particles. Components of these data structures are addressed 
by trailing selections, such as :p for the four momentum of a particle. Therefore 
the first line in the following action calculates the Mandclstam variable s fr om 



the four momenta of the two beam particles @B1 and @B2. See section |A.2| for 
more details on the available data types. 



-C 

S = (@Bl:p + @B2:p)~2; # Center of mass energy 



Next we loop over all outgoing electrons and store the momentum in $el. 

for (<5p in ELECTRONS) # Collect the outgoing electron. 
$el = @p:p; 

This method of obtaining the outgoing electron momentum is actually quite 
naive and uses the fact that the Monte Carlo KR0N0S will generate one and 
only one electron. A more sophisticated example would have to use some phys- 
ical criteria for distinguishing the scattered electron from electrons created in 
hadronic decays. An example would be to select the electron which is furthest 
away from any hadronic jet. Similar code selecting the hardest photon can be 



found in section 2.2.2 



In the next step the electron momentum is used to calculate the (electronic) 
momentum transfer and the usual Bjorken variables x,y. 

$q = @Bl:p - $el; # (Electronic) momentum transfer 

02 = - $q~2; 

x = Q2/(2*$q*@B2:p) ; # Bjorken variables 
y = Q2/(x*S); 



Finally the same naive method is used to determine the single outgoing quark 
momentum. 

for (@p in QUARKS) # Collect the outgoing quark (= jet) . 

$jet = @p:p; 

} 



2.2.3 Event processing 

After having determined the Bjorken variables in the last section, we can now 
use them for kinematical cuts. The next action will only be executed for those 
events that satisfy % m in. 1^ x < x max . and Q 2 > Q 2 min ■ Note that (unlike other 
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programming la ngua ges) comparisons can be combined to intervalls in a natural 
way. See section A. 5 for more details on comparisons and logical operators. 



(x_min <= x <= x_max) kk (Q2_min <= Q2) 
{ 

The first histogram will represent the total cross section inside the kinemat- 
ical cuts as a function of the photon multiplicity and the infrared cut off in the 
photon energy, hepawk version 1.6 does not have a for loop similar to C (for 
is at the moment only used for looping over particles), thus we implement the 
loop over the cut offs with a while loop. 

E_cut = 0.0; 

while (E_cut <= E_cut_max) 
{ 

For each cut off energy we now loop over all photons and select those that 
satisfy the energy cut and the angular cuts. 

i = 0; # multiplicity counter 
for (<3p in PHOTONS) 
if (@p:p:E >= E_cut) 
{ 

A photon is counted if it falls either in the forward or backward luminosity 
monitor or in the main detector. Furthermore it has to be sufficiently separated 
from the outgoing electron and quark jet. 

theta = angle (@p:p, @Bl:p); 

if ( (th_min_lumi <= theta <= th_max_lumi # bwd 

I I th_min_lumi <= PI - theta <= th_max_lumi # fwd 
I I th_min_main <= theta <= th_max_main) # main 

kk angle (@p:p, $quark) >= th_sep_jet 
kk angle (@p:p, $el) >= th_sep_em) 
i++; 

} 

Before reiterating the while loop, we fill the bin in the histogram corre- 
sponding to the measured multiplicity and the applied energy cut. 

fill (h_m, i, E_cut + 0.01); 
E_cut = E_cut + E_cut_step; 

} 



The other histograms record the energy spectrum of the hardest and second 
hardest photon in a multiphoton event. This is implemented by looping over all 
existing photons satisfying a certain energy cut and satisfying the same angular 
and separation cuts as above. 

n = 0; $p_hard = $p_soft = $NULL; 
for (fflp in PHOTONS) 
{ 

if (@p:p:E >= E_min) 
{ 

theta = angle (<3p:p, @Bl:p); 

if ( (th_min_lumi <= theta <= th_max_lumi # bw lumi 

I I th_min_lumi <= PI - theta <= th_max_lumi # fw lumi 



I I th_min_main <= theta <= th_max_main) # main 

&& (angle (@p:p, $quark) >= th_sep_jet) 
&& (angle (@p:p, $el) >= th_sep_em)) 

{ 

If the current photon is harder than the second hardest photon seen in the 
event so far, update the variables holding the momenta of these two photons. 

if (@p:p:E > $p_hard:E) # the hardest photon yet 

{ 

$p_soft = $p_hard; $p_hard = @p:p; 

y 

else if (@p:p:E > $p_soft:E) # the second hardest 

$p_soft = @p:p; 
n++; 

} 

} 

} 

Once we have decided which are the hardest photons in this event, we can 
fill the corresponding histograms. Furthermore a counter is incremented which 
will later be used to determine the accumulated cross section. 

if (n == 0) 

incut_0++; # count this event 

else if (n == 1) 

{ 

incut_l++; # count this event 
fill (h_E, $p_hard:E); 

} 

else 
{ 

incut_2++; 

fill (h_El, $p_hard:E); fill (h_E2, $p_soft:E); 
fill (h_El_E2, $p_hard:E, $p_soft:E); 

} 

} 



2.2.4 The END action 

The END action will be executed after the last event has been processed. Typi- 
cally it is used to print results and to write histograms to a permanent storage 
medium. Multiple instances of the END action will be concatenated. 

This END action starts by printing the integrated cross sections for zero, one, 
and multi photon events. These are constructed from the counters incremented 
earlier, the total number of scanned events, and the total cross section. The 
latter two variables are provided by the Monte Carlo in /hepevt/. 

END 
{ 

printf ("null photon events: °/,d, cross section: °/,gnib\n" , 

incut_0, ( incut _0/NEVENT) * XSECT) ; 
printf ("one photon events: °/„d, cross section: °/,gmb\n" , 

incut_l, ( incut _ 1 /NEVENT) * XSECT); 
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printf ("two photon events: °/,d, cross section: °/,gmb\n" , 
incut_2, ( incut _2/NEVENT) * XSECT) ; 

Now a line printer style plot of the histograms is printed out. 

printf ("\nHISTOGRAMS : \n") ; 
printf ("***********\n\n") ; 
plot Q; 

And finally the contents of the histograms is normalized to picobarns per 
bin and written to the file "PAW". 

scale (1.0e9 * XSECT/NEVENT) ; # normalize to picobarns 

save ("PAW") ; 

printf ("\ndone . \n") ; 



3 FORTRAN-77 Interface 

hepawk reads all information from the standard /hepevt/ common block 
If the Monte Carlo writes its output into /hepevt/, the FORTRAN-77 interface 
is as simple as the example in figure [l]. After the event generator (gener) has 
filled the common block, hepawk is called with the argument 'scan' to analyze 
it. An explicit initialization call is not necessary, but useful to catch syntax 
errors in the script before costly computations by the event generator have been 
performed. 

In addition to the standard described in hepawk requires the incoming 
particles to be stored in /hepevt/ too. Following the HERWIG convention ||, 
they must have the status codes 101 and 102 respectively. 

* mctest.f 

call hepawk ( ' init ' ) compile the script 

do 10 n = 1, nevent 

call gener () generate an event 

call hepawk ('scan') analyze the event 

10 continue 



Figure 1: FORTRAN-77 interface 

In order to avoid possible clashes in the FORTRAN-77 name space, all names 
of external symbols (functions, subroutines, and common blocks) are of the form 
1 hk . . . . ' or 1 hep . . . ' . An exception of this rule are the external symbols of 
the parser, with have been given the traditional 'yy. . . ' names. 

hepawk version 1.6 relies on the standard /hepevt/ common block and the 
HBOOK|| histo gramming package. It should be stressed, however, that both 
are accessed through a set of interface subroutines ('hep. . . ' for /hepevt/ 
and 'hkh. . . ' for HBOOK), such that using a different common block for 
passing the event information and using a different histogramming package can 
be implemented straightforwardly. 
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4 Implementation 



In this section we discuss the implementation of hepawk. This discussion is 
rather detailed in order to show how similar interpreters could be implemented 
along the same lines. 

A straightforward interpreter which would translate the script over and over 
again for each event scanned is of no use for applications in high energy physics, 
because of performance considerations. Therefore hepawk first compiles the 
script into code for a stack machine, which is in turn executed for each event. 
Parsing is done by a LALR(l) parser (see e.g. jjj), generated by a customized 
version of Bisonjl(j which has been modified to produce FORTRAN-77 code. Bi- 
son has been chosen, because it is available as freely redistributable source code 
and we had to make some changes in order to support FORTRAN-77 parsers. 
Bison is compatible to the parser generator YACC jLlJ, which is standard in 
UNIX environments. 

The following subsections describe in detail the implementation of the three 
main components of hepawk: lexical analysis, parser, and stack machine. 

4.1 Lexical Analysis 

Lexical analysis in hepawk is very simple. The lexical analyzer splits the input 
into tokens and passes them on to the parser for syntactical analysis. Comments 
are ignored and multiple whitespace (blanks, tabs and newlines) is converted to 
single blanks (but the location of the tokens is remembered for reporting errors). 

Lexical analysis is further simplified by using lexical conventions for the dif- 
ferent types of data. All variables denoting a four vector have to start with 
a $ and all variables denoting a particle have to start with a @. Another ap- 
proach would have been to require the declaration of data types (e.g. vector 
q; particle p; , etc.), but it is not desirable to require this overhead in hepawk 
scripts. 

4.2 Syntactical Analysis 

As already mentioned, the syntactical analysis is performed by an automatically 
generated, table driven LALR(l) parser. This approach has several important 
advantages over constructing a parser from scratch: 

• An automatically generated parser recognizes all valid sentences in the 
specified grammar and only those. It is far from trivial to achieve this by 
hand coding the parser. 

• Extending the grammar or changing parts of it can be done very easily. 
With a hand coded parser, a simple change might force the programmer 
to redesign the parser completely. 

• Table driven LALR(l) parsers do not require recursive subroutine calls 
to parse recursive expression grammars (this point is relevant to standard 
conforming FORTRAN-77 implementations). 

• Error handling is comparatively simple for LALR(l) parsers. 

• A LALR(l) parser is reasonably fast. 
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We will now illustrate the use of a parser generator by describing the imple- 
mentation of a particular language element in detail. In computer science our 
compilation method is known as "syntax directed translation" (see e.g. jj] for a 
general account). 

Figure shows a slightly simplified excerpt from the Bison grammar for 
hepawk in which the while control statement is implemented (see appendix AE 
for the full grammar). 



statement 



| "while" { 
call hkepos ($$) 



recognize reserved word 
remember current position 



"(" logicaLexpr ")" { 
call hkcasm ('JMPF') 
call hkedum ($$) 



parse condition 
jump if false 
address will be filled in below 



statement { 
call hkcasm ( ' JMP ') 
call hkcins ($2) 
call hkebek ($6) 



parse the loop body 
unconditionally jump back 
to the condition 
fill in the exit address 



Figure 2: Compiling while loops 

If we disregard the actions delimited by braces, it tells the parser genera- 
tor that a statement can be formed by the reserved word "while", a logical 
expression in parenthesis and a statement. 

After recognizing the reserved word "while", the first action instructs the 
parser to execute the FDRTRAN-77 statement call hkepos ($$), in which the 
parser generator will replace the symbol $$ by a reference to the top of the 
parser's stack. The subroutine hkepos will store there the address of the next 
instruction in the compiled program for later reference by the jump instruction 
at the end of the while loop. Now the parser will continue to parse the log- 
ical expression forming the condition of the while loop. During this parse it 
generates code to evaluate this condition, leaving the result on the top of the 
run-time stack. 

The second action instructs the parser to generate a conditional jump in- 
struction (call hkcasm ( ' JMPF ' ) ) which will jump out of the loop if the con- 
dition was false (i.e. if the value on top of the run-time stack is false). A place 
holder is generated for the address to jump to and its address is remembered 
on the parser's stack (call hkedum ($$)), so we can fill it in later. This is 
necessary, because we do not yet how long the following statement (which is 
usually a sequence of statements) will be. 

After parsing the statement and generating the corresponding code, the third 
action terminates the loop. The parser replaces the symbol $2 by a reference to 
the stack location where the first action (the second component of the produc- 
tion under consideration) has stored the entry address of the while loop. The 
FORTRAN-77 statement call hkebek ($6) finally "backpatches" the unresolved 
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address in the second action (the sixth component). 



4.3 Stack Machine 



The stack machine executes the "machine code" stored by the parser in an 
array of integers. Evaluation of expressions is performed by straightforward 
manipulations of operands in a sufficiently large run time stack. 

As an example of the code for the stack machine we will discuss the for 
loop which is used to loop over all particles in a given set. Figure || shows the 
actual code for a for loop. Before entering the for loop, a is pushed on the 
stack. If the BIND instruction finds a on the stack, it fetches the first particle 
belonging to the desired set from /hepevt/ and stores it at an address where 
the body of the loop can access it. If there are no more particles from the set, 
BIND pushes a FALSE and the next instruction jumps out of the loop. After the 
body has been executed, a 1 is pushed on the stack causing the next BIND to 
fetch the next particle. 



continue: 



exit: 



PSHP 







BIND 



particle 



set 



JMPF 



exit 



PSHP 



1 



JMP 



continue 



Push a 

Intrinsic function binding local variables 
Address holding particle 's properties 
Set to loop over 

Jump out of the loop when done 



Code to execute for each particle 
Push a 1 
Restart the loop 



Figure 3: Implementation of for loops 



4.4 Timings 

The time spent in the compilation step is certainly negligible and does not call 
for further optimizations. Most of this time is consumed by the lexical analyzer 
and can not be reduced portably anyway. A typical 180 lines hepawk script 
takes about 140ms to compile on a IBM RS/6000 (Model 520). 

On the other hand, the time spent executing the code is not negligible. 
Measurements on a IBM RS/6000 have shown that the execution time of the 
equivalent straight FORTRAN-77 program will roughly be multiplied by a factor 
of three. The aforementioned 180 lines hepawk script takes about 0.6 msec to 
execute, where 0.2 msec are due to scanning of the /hepevt/ common blocks and 
to library calls (HBOOK). Since the equivalent FORTRAN-77 program will have 
to perform the same tasks, the remaining 0.4 msec can serve as a conservative 
estimate on hepawk's execution time. 
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Future versions will take advantage of some optimizations and should be 
able to reduce the computational overhead to a factor of two. 

5 Future Developments 

hepawk has been developed in the context of a specific project: the construction 
of a parton level Monte Carlo event generator for HERA physics. Nevertheless 
it has been designed to meet more general requirements and should be easily 
adapted to different applications. Indeed, since the release of version 1.0 hepawk 
has been be a useful tool in the development of the KROWIG Monte Carlo fl2|| , 
proving that it can deal conveniently and efficiently with hadronic final states. 
Amongst possible future developments for hepawk are: 

• User definable functions (subroutines): these would allow to group com- 
monly used kinematical calculations into a subroutine library. 

• Arrays: most likely these will be implemented as associative arrays, and 
the for statement will allow to loop over all elements. In connection with 
user definable functions it will for example be possible to sort these arrays 
according to some prescription. 

• More physics: hepawk's syntax can be extended to admit jet finding algo- 
rithms, etc. 

• Optimization: for the sake of simplicity, some language elements are com- 
piled sub-optimally in hepawk version 1.6. Although there shall be no 
dramatic increase in running time, some improvements are possible, espe- 
cially for complicated logical expressions. 

6 Conclusions 

We have described the implementation of hepawk version 1.6, a programming 
language for scanning data structures in high energy physics. Implemented in 
FORTRAN-77, this language is completely portable and can be used with any 
Monte Carlo event generator which writes standard event records. 
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A Reference Manual 

This appendix serves as a reference manual for hepawk version 1.6. 
A.l Input files 

The input files are in free format (record separators are ignored apart from 
terminating comments) . But to allow identical operation on all computers used 
in high energy physics, the maximum length of input lines has been restricted 
to 72. 

A. 2 Data types 

x_elec_l 

Scalar variable. 

$p 
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p is a four- vector. 

:1, :2, :3, :4, :0, :x, :y, :z, :E, :t 

Extract a component from the preceding four- vector (:0, : 4 , :E, :t are 
different names for the time like component, :3, :z are different names 
for one of the beam directions. For example $p : E and $p : both refer to 
the energy component of the four vector $p. 

@p 

p is a particle (with four-momentum, production vertex, and spin in the 
fashion of /hepevt/Q). 

:id, :p, :v, :s 

Extract the PDG code|l3|], the four-momentum, vertex, and spin vector 
from the preceding particle. For example @p:p and @p:p:E refer to the 
four momentum and the energy of the particle Op. 

A. 3 Statements 

BEGIN, END 

Special tokens, indicating that the following statement is executed only 
during initialization and clean up. 

{. } 

Start and terminate a group of statements. 

Terminates a statement, (hepawk does not recognize newline as a state- 
ment terminator!) 

A. 4 Control Structures 

if (condition) statement 

Execute statement if condition is true. 

if (condition) statementA else statement-2 

Execute statementA if condition is true, if not execute statement-2 . 

while (condition) statement 

Repeatedly execute statement while condition is true. 

for (^particle in set) statement 

Execute statement for each particle in set. Available sets are: QUARKS, 
LEPTONS, PHOTONS, HADRONS, ELECTRONS. 

next 

Terminate execution of the script here and wait for the next record, 
break 
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Jump out of the innermost enclosing for or while loop, 
continue 

Restart the innermost enclosing for or while loop. 
A. 5 Operators 

Binary arithmetical assignment operator. 

Unary arithmetical operator: negative (— ). 
+ — * / 

Binary arithmetical operators: sum (+), difference (— ), product (*), quo- 
tient (/), and power (x y ), resp. cross product. Products of four-vectors 
are either (lorentzian) inner, (three dimensional) cross or scalar product. 
Divison of four-vectors is availabe as right scalar division, division is not 
available for four-vectors. The power operator for four-vectors is defined 
as (v) a = sign(v • v)\v ■ v\ a ^ 2 . Note that v 4 ^ (v 2 ) 2 for spacelike v. 

+= -= *= /= 

Binary arithmetical operators with assignment (i.e. a+=b=a=a+ 
b). These are at the moment not more efficient than the long form, just 
more concise (this may change in future releases). 

++, — 

Unary increment and decrement operator. Like C we distinguish post 
increment from pre increment (resp. decrement). x++ has the same effect 
as x = x + 1, but is more concise and slightly more efficient. 

! 

Unary logical operator: not (^). 
&&, I I 

Binary logical operators: and (A), or (V). 

==, !=, <, <=, >, >= 

Binary arithmetical comparison operators: equal (=), not equal (7^), less 
than (<), less than or equal to (<), greater than (>), greater than or 
equal to (>). Unlike most other programming languages these operators 
can be combined to form intervals, thus 0.01 < x < 0.5 is a well defined 
condition in hepawk. This expression is identical to0.01<x&&x< 
0.5, but x is evaluated only once. Furthermore even 0.01 < x_l <= x_2 
< . 5 is legal and has the obvious semantics. Please note that version 1.6 
of hepawk docs not optimize the evaluation of logical expressions in the 
way C does it. This may change in a future version. 

/I 
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A operator, implementing a Lorentz boost: $q = $p /I $beta corre- 
sponds to 



A. 6 Builtin Constants 

ALPHA 

Fine structure constant chqed = 1/137.03599. 

DEG 

Degrees per radians: I8O/71-, this is useful if you prefer angular cuts in 
degrees: 10/DEG < angle ($p, @Bl:p). 

GAMMA 

Euler's 7 = 0.577215664901532861. 
HBARC 

Conversion factor he = 197.3271 MeV fm. 

HBC2 

Conversion factor (he) 2 = 0.3893797GeV 2 mbarn. 

PI 

The number tt = 3.141592653589793238. 

NULL, $NULL, (SNULL 

The number 0, the null four- vector (0; 0, 0, 0), and a particle with all com- 
ponents 0. 

$E1, $E2, $E3, $E0 

Unit four-vectors (0; 1,0,0), (0; 0,1,0), (0; 0,0,1), (1; 0,0,0). Available 
aliases are $EX , $EY, $EZ, $ET, $EE, $E4. 

_pdg_electron, _pdg_proton, . . . 

Symbolic names for some PDG |ll| particle codes. Also available are (to 
be prefixed by _pdg_): down, up, strange, charm, bottom, top, electron, 
nu_e, muon, nu_m, tau, nu_t, gluon, gluon_, photon, ZO, W_plus, higgsO, 
higgsp, piO, eta, K_plus, KO, KCLshort, K0_long, proton, neutron. 

A. 7 Automatic variables 

These variables are initialized automatically for each record, hepawk follows the 
HERWIG convention || and recognizes the first two entries with status code 101 
and 102 as beam particles. The user is responsible for providing these. 

OBI , @B2 



1 
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i-0 2 




18 



The two incoming (beam) particles. 
NEVENT 

The current event number. In END actions this is the total number of 
events. 

XSECT 

The total generated cross section in mb. Non-zero in END actions only. 
ERROR 

The Monte Carlo error (in mb), as estimated by the calling Monte Carlo 
event generator. Non-zero in END actions only. (NB: this variable is only 
defined, iff the calling Monte Carlo stores the error in phep(l,2) ; which 
is not required by the standard). 

MC 

Monte Carlo identification number (as in /hepevt/). 

REV 

Monte Carlo Version formatted as string. 

RUN 

Run identification number. 

DATE 

Date of run formatted as string. 

A. 8 Builtin Functions 

A. 8.1 Arithmetic 

sin (x) , cos (x) , tan (x) 

Returns the sine, cosine, tangent of x. 

asin (x) , acos (x) , atan (x) 

Returns the inverse sine, cosine, tangent of x. 

atan2 (x , y) 

Returns the inverse tangent of y/x. 

abs (x) 

Returns the absolute value \x\ of x. 

sqrt (x) 

Returns the square root of x. 

ssqrt (x) 

Returns sign(x) • y/x. This is useful in ssqrt ($q*$q) , if q might be space- 
like. 

log (x) , loglO (x) , exp (x) 
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Returns the logarithms to base e and 10 and the exponential of x. 
angle ($p, $q) 

Returns the angle between the spatial parts of the four-vectors p and q. 

angle(p, q) = acos f -^ (1) 

rap , prap , pt ($p) 

Rapidity, pseudo rapidity, and transverse momentum of the four- vector p. 

rap(p) = y(p) = - In ( P ° + P3 ) (2) 
2 \P0-P3J 

prap(p) = ^) = -ln(tan(iz(p,e 2 ))) (3) 



Pt(p) = V^ +p 2 ( 4 ) 

dist $g) , pdist ($p, $q) 

Distance of the four-vectors p and q in rapidity space (resp. pseudo ra- 
pidity space). 



dist(p,?) - ^(Ay) 2 + (A0)2 (5) 
pdist(p,g) = V(&V) 2 + (A^) 2 (6) 

A.8.2 Output 

printf (format, argl , arg2 , argS , ...) 

Print the arguments according to the format specified in format. The 
following formats and escapes are implemented in hepawk version 1.6: 

• °/ d: integer. 

• °/ e , %f , %g: floating point number in exponential, fixed, or mixed 
representation. 

• 7 s: string. 

• °/ v, °/ u, °/ w: floating point four-vector in the format (vq] v±, V2, V3) 
in exponential, fixed, or mixed representation. 

• \n: insert newlinc. 

It is likely that future versions of hepawk will allow to specify field widths 
in the format string. 

A. 8. 3 Miscellaneous 
rand ( ) 

Return a on the intervall [0, 1] uniformly distributed random number, 
generated by the algorithm of [Q . 

rseed (ijseed , klseed) 
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Reinitialize the random number generator with the seeds ijseed (mod 
31329) and klseed (mod 30082). 

unidev (/!, er) 

Return a on the intervall \p — a, fi + a] uniformly distributed random num- 
ber. Note that a 2 is not the second moment of the generated distribution. 

gauss (/!, cr) 

Return a gaussian distributed random number with mean /j, and standard 
deviation a. See figure ^ for a sample application. 

charge (?) 

Calculate the charge of a particle from its PDG[jl3| code i, see figure | for 
a sample application. 

dump (flags ) 

Dump the current event completely. This can be useful for debugging. The 
optional string flags can be used to suppress some output: p: momenta, 
v: production vertex, s: spin, m: mothers, d: daughters, and r: reserved 
status codes. 

exit () 

Terminate the program bye executing a FORTRAN-77 STOP instruction. 



# charge .hepawk 
"{ 

for (Op in HADRONS) select hadrons 

if (rand () < 0.9 && charge (Op: id)) select charge 

{ with 90% efficiency 

energy = @p:p:E; naive energy 
energy = gauss (energy, 0.16 * sqrt (energy)); calorimeter 

fill (charged_tiadrons , energy); detected 



Figure 4: Charged particles 



A. 8. 4 Histogramming 

bookl (n, title, i, x m i n , x max ) 
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Book a one-dimensional histogram with identifier n, title title, and i chan- 
nels in the interval [a; m i n , x maK ] . Only the identifier is required, for the 
other parameters the following defaults are provided: title = " ", i = 100, 
[aJmin, £max] = autoscaling. This and the following booking functions re- 
turn the identifier of the booked histogram. This is useful for the special 
argument n < 0, in which case a unique identifier will be created by 
hepawk. 

book2 (/I, title, i, X m [ n , 2)niax) j> ym'm> 2/max) 

Book a two-dimensional histogram with identifier n, title title, i channels 
in the interval [x m i n , x max ], and j channels in the interval [y m i n , y max ]. All 
parameters are required. 

bookl (n, title, i, x nl[n , x max ) 

Book a one-dimensional histogram with identifier n, title title, and i chan- 
nels in the interval [x m i n , x max ]. These channels will be logarithmically 
equidistant. All parameters are required. 

bookp (n) 

Book the projections for the two-dimensional histogram n. (n = applies 
to all two-dimensional histograms booked so far.) 

fill (n, x, y) 

Fill the point (a;, y) into the histogram n. If y is not supplied, it defaults 
to 0. 

plot (n) 

Plot the histogram n in lincprinter format. If n is not supplied, it defaults 
to 0, which means plot all booked histograms. 

scale (n, [i) 

Rescale the contents of histogram number n by the factor /x. This function 
is convenient for normalizing histograms to total cross sections, since the 
latter usually are available only after the run. The abbreviation scale 
(/i) is equivalent to scale (0, which means rescale all histograms. 

arith (n, i\ , op, i 2 , x lt x 2 ) 

Perform arithmetic on the histograms i\ and i 2 - If x{k',l) denotes the 
contents of channel I of histogram k, then we have 

X(n;l) = X!x(ii;l)opx 2 x(i2;l) (7) 

and op is one of +, -, *, or /. Iff n = a new histogram is allocated and 
its number is returned. 

copy (n, i, title) 

Copy histogram i to histogram n, optionally changing the title to title. Iff 
n = 0a new histogram is allocated and its number is returned. 

delete in) 
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Delete histogram n, with n = meaning all histograms. 

save (filename) 

Save the current directory in the permanent file filename. 

open (filename, directory, mode) 

Open the RZ file filename and connect it to the RZ directory directory. 

close (directory) 

Close the RZ file connected to the RZ directory directory. 

read (n, cycle, offset) 

Read the cycle cycle of histogram n from disk into histogram n + offset. 
Default value for offset is and 9999 for cycle, (cycle and offset might 
not be supported with other histogramming packages than HBOOK.) 

write (ri) 

Write the histogram n to disk. 

mkdir (dir) 

Create the subdirectory dir. 

cd (dir) 

Change the working directory to dir. 
Is (dir) 

List the contents of the directory dir, this defaults to the current working 
directory. 

A. 8. 5 Graphics 

These experimental features were new with version 1.4 and have disappeared 
with version 1.6. 

display ((f), 9, r, device, filename) 
Do nothing. 

A. 9 Grammar 

The following is a complete description of the grammar understood by hepawk 
version 1.6. This grammar has two harmless ambiguities, which result in so 
called "shift/reduce" conflicts for the parser. The first ambiguity is caused 
by the standard "dangling else" Q problem. The second ambiguity is caused 
by accepting real expressions as logical expressions. The parser cannot decide 
whether it should convert the real expression in if ( (real) ) to logical before or 
after parsing the parenthesis. But since parsing the parenthesis does not cause 
a semantic action, this ambiguity can be ignored. 

A complete hepawk script is a - possibly empty - sequence of actions, where 
an action is essentially a brace delimited sequence of statements. If it is preceded 
by a logical expression, the action is executed only if this logical expression 
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evaluates to true. The simplest statements are scalar or vector expressions, 
terminated by a semicolon. Furthermore statements can be combined with 
conditionals and be grouped by braces. Logical expressions can be combined by 
the usual operators. An unsual feature is the possibility to combine numerical 
comparisons to ranges (e.g. 10~ 3 < x < 0.1). A single real is regarded as true 
if and only if it is not zero. The usual rules for real arithmetic apply, enriched 
by pre- and postincrement, function calls and structure members, similarily for 
vector arithmetic. Finally, arguments to functions are a - possibly empty - 
comma separated list. 



A. 9.1 Tokens and Operators 

This is a complete list of all tokens and operators on hepawk version 1.6. Oper- 
ators are sorted according to increasing priority. 

• tokens: "if" "else" "while" "for" "in" SET "next" "break" "continue" 
"BEGIN" "END" "(" ")" "{" "}" "," " ; " SCALAR VECTOR VECTC 
PARTCL PARTV PARTS FCTN STRING 

• right associative: " = " "+=" "-=" "*=" "/=" 

• left associative: " II " 

• left associative: 

• left associative: RELOP 

• left associative: " + " "-" 

• left associative: "*" "/" 

• left associative: NEG " ! " 

• left associative: "/I" 

• right associative: "~" 

• left associative: "++" " — " 



A. 9. 2 Grammar 

Here is the list of all productions in the hepawk grammar (this replaces the 
syntax diagrams of (sj): 

scripts /* empty */ 

script action 

actions beg_or_end "{" stmtJist "}" 

| "{" stmtJist "}" 

| log_expr "{" stmtJist "}" 
beg_or_end^ "BEGIN" 

| "END" 
stmtJist^ /* empty */ 

stmtJist stmt 
stnnw error " ; " 
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vector_expr- 



"next" ";" 
"break" " ; " 
"continue" " ; " 

reaLexpr " ; " 

vector_expr " ; " 

iLclause stmt 

iLclause stmt "else" stmt 

"while" "(" log.expr ")" stmt 

"for" "(" PARTCL "in" SET ")" stmt 

"{" stmUist "}" 

"if" "(" log.expr ")" 

"(" log.expr ")" 

log_expr log.expr 

log_expr "II" log.expr 

" ! " log_cxpr 

reaLexpr 

range 

reaLexpr RELOP reaLexpr 
range RELOP reaLexpr 
SCALAR 

VECTOR VECTC 
PARTCL PARTS 
PARTCL PARTV VECTC 
"++" reaUval 
" — " reaUval 
reaUval "++" 
reaUval " — " 
reaUval " = " reaLexpr 
reaUval "+=" reaLexpr 
reaUval "-=" reaLexpr 
reaUval "*=" reaLexpr 
reaUval "/=" reaLexpr 
vector_expr "*" vector _expr 
vector_expr " " reaLexpr 
FCTN "(" argjist ")" 
FCTN "(" error ")" 
"(" reaLexpr ")" 
"-" reaLexpr %prec NEC 
reaLexpr " + " reaLexpr 
reaLexpr "-" reaLexpr 
reaLexpr "*" reaLexpr 
reaLexpr "/" reaLexpr 
reaLexpr " " reaLexpr 
SCALAR 

VECTOR VECTC 
PARTCL PARTS 
PARTCL PARTV VECTC 
VECTOR 
PARTCL PARTV 
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vectJval " = " vector _expr 
vectJval "+=" vector_expr 
vectJval "-=" vector_expr 
vectJval "*=" reaLexpr 
vectJval "/=" reaLexpr 
" ( " vector _expr " ) " 
"-" vector _expr %prec NEG 
reaLexpr "*" vector_expr 
vector_expr "*" reaLexpr 
vector_expr "/" reaLexpr 
vector_expr " + " vector _expr 
vector_expr "-" vector _expr 
vector_expr " / 1 " vector _expr 
VECTOR 
PARTCL PARTV 
STRING 
/* empty */ 
arg 

argJist " , " arg 
reaLexpr 
vector_expr 
string_expr 

A. 10 FORTRAN-77 Interface 

hepawk is defined as a FORTRAN-77 subroutine with a single argument: 

* hepawk . f 

subroutine hepawk (opcode) 
character*4 opcode 

end 

If the argument is 'init', hepawk initializes itself and compiles the script. 
If the argument is 'scan' normal processing is done. 

It is not necessary to initialize hepawk explicitly (it will initialize itself during 
the first call). Anyway it is recommended to compile the script before any 
expensive calculations are performed in the calling program, in order to catch 
possible syntax errors. 

hepawk expects to find the event in the standard /hepevt/ common blockQ. 

All symbols exported by the hepawk library are named ' hk . . . . ' , 1 yy . . . . ' , 
or 'hep . . . ' . 

B Test Run 

B. l Test program 

This is a simple test program for testing hepawk without a full Monte Carlo 
Event generator. The program reads the data for some particles from standard 
input and stores it in /hepevt/. 



vectJval—* 

string_expr- 
argJist^ 



arg- 
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c Very simple test driver, reading an event from unit 5 with an 

c arbitrary number of particles in the format: 

c 

c id status pi p2 p3 pO m 

c vl v2 v3 vO si s2 s3 
c 

c 2212 102 0.00 0.00 -820.00 820.00 0.00 

c 0.00 0.00 0.00 0.00 0.00 0.00 0.00 

program test 
implicit none 

integer hepent 

integer n, type, status 

double precision p(5) , v(4) , s(3) 

c compile the script 

call hepawk ( ' init ' ) 



c 


trigger BEGIN action 


c 


MC id: 


190416 


c 


MC rev: 


1.37 


c 


MC date: 


01/01/91 


c 


Run id : 


2200 


c 


Run date: 


01/02/91 


c 


Run time: 


12:00 



call hepeni (190416, 137, 910101, 2200, 910102, 120000) 
call hepawk ('scan') 

c read the event 

call hepnew (1) 
10 continue 

read (5, *, err=999, end=999) type, status, p 
read (5, *, err=999, end=999) v, s 
n = hepent (type, status, 0, p, v, s) 
goto 10 
999 continue 

c scan it 

call hepawk ('scan') 

c trigger END action 
c 1,000,000 events 
c 3. 14159 mbarn 

call hepens (1000000, 3.14159d0, 2.718281d0) 

call hepawk ('scan') 

end 

B.2 Test Input 

This is input for the above test program. 

11 101 0.00 0.00 30.00 30.00 0.00 



27 



0.00 


0.00 





00 





00 





00 





00 





00 


2212 


102 





00 





00 


-820 


00 


820 


00 





00 


0.00 


0.00 





00 





00 





00 





00 





00 


11 


1 


10 


00 


-5 


00 


25 


00 


27 


39 





00 


0.00 


0.00 





00 





00 





00 





00 





00 


22 


1 


40 


00 


30 


00 


10 


00 


50 


99 





00 


0.00 


0.00 





00 





00 





00 





00 





00 



B.3 Test Script 

Some errors have been deliberately built in to test the error reporting routines. 

BEGIN 
{ 

printf ("Welcome to the HEPAWK test suite ! \n\n") ; 

printf ("You *should* have seen a syntax error above\n") ; 

printf ("complaining about a misplaced continue statement ! \n\n") ; 

continue; # HEPAWK will complain 

printf ("The following PDG codes should match: \n"); 
printf (" Particle PDG Code Charge\n"); 

printf (" electron °/,d = 11 'Id = -1.0000\n", 

_pdg_electron, charge (_pdg_electron) ) ; 
printf (" proton 7,d = 2212 °/.f = 1.0000\n", 

_pdg_proton, charge (_pdg_proton) ) ; 
printf ("\n"); 

printf ("Expect a runtime error (division by zero) here:\n"); 
1/0; 

printf ("Expect another runtime error (invalid argument) here:\n"); 
loglO (-1.0); 
printf ("\n"); 



# The following checks crucially depend on the proper input data. 



printf 


( 


'Analyzing event 


#y.d:\n", NEVENT) ; 




printf 


( 


1 Beam #l:\n") ; 






printf 


( 


1 PDG code: 


7.d (= ll)\n", 


@Bl:id) ; 


printf 


( 


1 momentum: 


•/.v\n", ®Bl:p); 




printf 


( 


1 Beam #2:\n") ; 






printf 


( 


1 PDG code: 


7.d (= 2212) \n" 


, @B2:id); 


printf 


( 


1 momentum: 


•/.v\n", <3B2:p); 




printf 


( 


1 Outgoing electron : \n" ) ; 




for (Qe 


; in ELECTRONS) 







printf 


(" 


momentum: 


7.v\n" 


( 


3e:p); 






printf 


(" 


pt: 


Xe (= 





1118E+02)\n" , 


pt ( 


@e:p)) ; 


printf 


(" 


rapidity: 


•/.e (= 





1544E+01)\n", 


rap 


(@e:p)); 


printf 


(" 


pseudo rapidity: 


Xe (= 





1544E+01)\n", 








prap 


«3e:p)); 












printf 


(" 


angle (deg) : 


y.e (= 





2409E+02)\n", 
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DEG * angle (@e:p, @Bl:p)); 

} 

printf (" Outgoing photon:\n"); 
for (Qp in PHOTONS) 
{ 

printf (" momentum: 7.v\n" , @p:p); 

printf (" pt: 7.e (= . 5000E+02)\n" , pt (Qp:p)); 

printf (" rapidity: 7.e (= . 1987E+02)\n" , rap (fip:p)); 

printf (" pseudo rapidity: '/.e (= . 1987E+02) \n" , 
prap (@p:p)); 

printf (" angle (deg) : "/.e (= 0.7869E+02)\n" , 

DEG * angle (@p:p, <SBl:p)); 

> 

printf (" Photon-Electron subsystem: \n") ; 

printf (" invariant mass: */.e (= . 1793E+04) \n" , 

(@p:p + @e:p)~2) ; 
printf (" rapidity dist . : °/.e (= . 1742E+01) \n" , 

dist (@p:p, @e:p)); 
printf ("\n"); 

} 

BEGIN 
{ 

printf ("That's the end of the BEGIN actions ! \n\n") ; 

} 

END 
{ 

printf ("Finally the END actions : \n\n") ; 
if (10 > PI) 

printf ("Conditions work!\n"); 
else 

printf ("Conditions are buggy!\n"); 

printf ("Counting to three:"); 
i = 1; 

while (i <= 3) 

printf (" Id" , I 
printf (".\n\n"); 

printf ("Summary : \n") ; 

printf ("number of events : 7.d (= 1000000)\n", NEVENT) ; 
printf ("cross section (mb) : "/.e (= . 3142E+01)\n" , XSECT) ; 

printf ("That's it.\n"); 

} 



B.4 Sample Output 

This is the output from the above test job. 

hepawk: message: starting HEPAWK, Version 1.00/00, (build 911013/1931) 
hkcbrk: error: continue outside of for or while loop, ignored 
Welcome to the HEPAWK test suite ! 
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You *should* have seen a syntax error above 
complaining about a misplaced continue statement! 

The following PDG codes should match: 
Particle PDG Code Charge 

electron 11 = 11 -1.0000 = -1.0000 

proton 2212 = 2212 1.0000 = 1.0000 



Expect a runtime error (division by zero) here: 
hkeerr: error: division by zero (result: 0.0): 
19: 1/0; 

<> 

Expect another runtime error (invalid argument) here: 
hkeerr: error: negative argument (using absolute value). 
21: loglO (-1.0); 



That's the end of the BEGIN actions! 



Analyzing event # 1 : 

Beam #1: 

PDG code: 11 

momentum : (0 . 30E+02 ; 

Beam #2: 

PDG code: 2212 

momentum: (0.82E+03; 

Outgoing electron: 

momentum : (0 . 27E+02 ; 

pt: 0.1118E+02 

rapidity: 0.1544E+01 

pseudo rapidity: 0.1544E+01 

angle (deg) : 0.2409E+02 

Outgoing photon: 

momentum: (0.51E+02; 

pt : . 5000E+02 

rapidity: 0.1987E+00 

pseudo rapidity: 0.1987E+00 

angle (deg): 0.7869E+02 

Photon-Electron subsystem: 

invariant mass: 0.1793E+04 

rapidity dist . : 0.1742E+01 



(= ID 

0.00E+00, 0.00E+00, 0.30E+02) 
(= 2212) 

0.00E+00, 0.00E+00, -.82E+03) 

0.10E+02, -.50E+01, 0.25E+02) 
(= 0.1118E+02) 
(= 0.1544E+01) 
(= 0.1544E+01) 
(= 0.2409E+02) 

0.40E+02, 0.30E+02, 0.10E+02) 
(= 0.5000E+02) 
(= 0.1987E+02) 
(= 0.1987E+02) 
(= 0.7869E+02) 

(= 0.1793E+04) 
(= 0.1742E+01) 



Finally the END actions: 



Conditions work! 

Counting to three: 1 2 3. 

Summary : 

number of events : 1000000 (= 1000000) 
cross section (mb) : 0.3142E+01 (= 0.3142E+01) 
That's it. 
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C Revision History 

Version 1.6, March 1995 

• Disabled feature: 

— Abandoned simple graphics support (identified as "creeping featur- 
ism"). 

• Miscellaneous: 

— Improved configuration and portability. 

— Small bug fixes. 

Version 1.5, June 1994 

• Miscellaneous: 

— Improved configuration. 

Version 1.4, June 1994 

• New feature: 

— Simple graphics support. 

Version 1.3, February 1994 

• New syntactical features: 

— cross product ~. 

• Internal changes: 

— Make the 'BIND' instruction reentrant (this fixes a long standing 
(but unnoticed) bug. 

• Miscellaneous: 

— Convert from PATCHY to noweb and autoconf . Put all system depen- 
dencies into a single file. 

Version 1.2, June 1992 

• New syntactical features: 

— Lorentz boosts / I . 

— Assignment operators +=, -=, *=, and /=. 

— Structure and vector components are now lvalues. 

• New builtin functions: 

— arith () 

— copy () 

— delete () 
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Version 1.1, March 1991 

Maintenance release. 

• ERROR automatic variable. 

• All calculations are done in double precision. 

• Fixing a serious bug in the parser skeleton for yypars () : FORTRAN-77 is 
allowed to reorder statements in a conditional expression, this could cause 
an access violation in one of the parser tables (noticed on VAX Fortran). 

• This version has no more than 19 continuation lines in a single statement 
(FORTRAN-77 standard). 

• More extensive runtime error checking. 

• Minor bug fixes. 

Version 1.0, October 1991 

First official release, submitted to the Computer Physics Communication Li- 
brary. 

D Availability 

The latest release of hepawk is available by anonymous ftp from 

crunch. ikp.physik.th-darmstadt .de 
in the directory 

pub/ ohl/hepawk 
or on the World Wide Web at the URL 

\protect\vrule widthOpt\protect\href {http: // crunch. ikp .physik. th-darmstadt .de/monte 

E Installation 

E.l UNIX Systems 

On UNIX systems, the configuration, compilation and installation can be per- 
formed automatically according to the following familiar sequence: 

$ ./configure 
$ make 
$ make test 
$ make install 

Figure]^ shows the command line options of the configure script for hepawk 
on UNIX systems. This configure script has been created by the popular GNU 
Autoconf[^5) package and should work on all UNIX variants. 
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Usage: configure [options] [host] 

Options: [defaults in brackets after descriptions] 
Configuration: 



— cache-f ile=FILE 
— help 
— no-create 
— quiet, — silent 
— version 
Directory and file names 
— prefix=PREFIX 



cache test results in FILE 

print this message 

do not create output files 

do not print 'checking...' messages 

print the version of autoconf that created configure 



-exec-pref ix=PREFIX 



-srcdir=DIR 



install architecture-independent files in PREFIX 
[/usr/local] 

install architecture-dependent files in PREFIX 
[same as prefix] 

find the sources in DIR [configure dir or . .] 
— program-pref ix=PREFIX prepend PREFIX to installed program names 
— program-suf f ix=SUFFIX append SUFFIX to installed program names 
— program-transf orm-name=PROGRAM run sed PROGRAM on installed program names 
Host type : 

configure for building on BUILD [BUILD=HOST] 
configure for HOST [guessed] 
configure for TARGET [TARGET=HOST] 



— build=BUILD 
— host=H0ST 
— target=TARGET 

Features and packages: 
— disable-FEATURE 
— enable-FEATURE [=ARG] 
— with-PACKAGE [=ARG] 
— without -PACKAGE 
— x-includes=DIR 
— x-libraries=DIR 

— enable and 
— with-g77 
—with- 1 ibpath=P ATH 
— with-cernlib 
— enable-noweb 
— enable-bison 
— enable-paper-a4 
— enable-paper-us 



-with-P ACK AGE=no ) 



do not include FEATURE (same as 
include FEATURE [ARG=yes] 
use PACKAGE [ARG=yes] 
do not use PACKAGE (same as 
X include files are in DIR 
X library files are in DIR 
with options recognized: 

use GNU Fortran 77 
use PATH for libraries 
use CERNLIB 

use noweb(l) to rebuild Fortran sources 
use bison(l) to rebuild parser 
use European (A4) paper 
use US (letter) paper 



enable-FEATURE=no) 



Figure 5: Comandline options of the configure script for hepawk on UNIX 
systems. 
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E.2 Non-UNIX Systems 

For non-UNIX systems configuration and compilation has to be performed man- 
ually: 

• Copy the file conf ig . f . in to conf ig . f and edit it according to the com- 
ments. 

• If necessary, adapt the include statements in hepawk . f and hepawk . tab . f 
to your FORTRAN-77 compiler. 

• Compile the files hepawk. f, config.f and hepawk. tab. f. 

• Compile the file hktest.f and link the result with the other object files 
to create a simple test program. 
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